.TH std::rotate_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::rotate_copy \- std::rotate_copy

.SH Synopsis
   Defined in header <algorithm>
   template< class ForwardIt, class OutputIt >

   OutputIt rotate_copy( ForwardIt first, ForwardIt
   n_first,                                                 \fB(1)\fP (constexpr since C++20)

                         ForwardIt last, OutputIt d_first
   );
   template< class ExecutionPolicy,

             class ForwardIt1, class ForwardIt2 >
   ForwardIt2 rotate_copy( ExecutionPolicy&& policy,
                           ForwardIt1 first, ForwardIt1     \fB(2)\fP \fI(since C++17)\fP
   n_first,

                           ForwardIt1 last, ForwardIt2
   d_first );

   1) Copies the elements from the range [first, last), to another range beginning at
   d_first in such a way, that the element *(n_first) becomes the first element of the
   new range and *(n_first - 1) becomes the last element.
   2) Same as \fB(1)\fP, but executed according to policy.
   This overload participates in overload resolution only if

   std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true.        (until
                                                                             C++20)
   std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true. (since
                                                                             C++20)

   If any of the following conditions is satisfied, the behavior is undefined:

     * [first, n_first) or [n_first, last) is not a valid range.
     * The source and destination ranges overlap.

.SH Parameters

   first, last - the range of elements to copy
   n_first     - an iterator to an element in [first, last) that should appear at the
                 beginning of the new range
   d_first     - beginning of the destination range
   policy      - the execution policy to use. See execution policy for details.
.SH Type requirements
   -
   ForwardIt, ForwardIt1, ForwardIt2 must meet the requirements of
   LegacyForwardIterator.
   -
   OutputIt must meet the requirements of LegacyOutputIterator.

.SH Return value

   Output iterator to the element past the last element copied.

.SH Complexity

   Exactly std::distance(first, last) assignments.

.SH Exceptions

   The overload with a template parameter named ExecutionPolicy reports errors as
   follows:

     * If execution of a function invoked as part of the algorithm throws an exception
       and ExecutionPolicy is one of the standard policies, std::terminate is called.
       For any other ExecutionPolicy, the behavior is implementation-defined.
     * If the algorithm fails to allocate memory, std::bad_alloc is thrown.

.SH Possible implementation

   See also the implementations in libstdc++, libc++, and MSVC STL.

   template<class ForwardIt, class OutputIt>
   constexpr // since C++20
   OutputIt rotate_copy(ForwardIt first, ForwardIt n_first,
                        ForwardIt last, OutputIt d_first)
   {
       d_first = std::copy(n_first, last, d_first);
       return std::copy(first, n_first, d_first);
   }

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <iterator>
 #include <vector>

 int main()
 {
     std::vector<int> src{1, 2, 3, 4, 5};
     std::vector<int> dest(src.size());
     auto pivot = std::find(src.begin(), src.end(), 3);

     std::rotate_copy(src.begin(), pivot, src.end(), dest.begin());
     for (int i : dest)
         std::cout << i << ' ';
     std::cout << '\\n';

     // copy the rotation result directly to the std::cout
     pivot = std::find(dest.begin(), dest.end(), 1);
     std::rotate_copy(dest.begin(), pivot, dest.end(),
                      std::ostream_iterator<int>(std::cout, " "));
     std::cout << '\\n';
 }

.SH Output:

 3 4 5 1 2
 1 2 3 4 5

.SH See also

   rotate              rotates the order of elements in a range
                       \fI(function template)\fP
   ranges::rotate_copy copies and rotate a range of elements
   (C++20)             (niebloid)
